package com.ar4j.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Defines the behavior of a native SQL query method on an ActiveRecord 
 */
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface NativeSqlMethod {

  /**
   * @return the SQL query to run
   */
  String sqlQuery();
  
  /**
   * <code> 
   *   {@literal @}NativeSqlMethod(sqlQuery = "SELECT * FROM ... WHERE field1 = :prop1 AND field2 = :prop2", bindVariables = { "prop1", "prop2" })<br/>
   *   public SomeBean findByNamedQuery(String value1, String value2)<br/>
   * </code><br/>
   * 
   * in the above example the query is run and values for the bind variables prop1 and prop2 are set from the method's parameters. The order in 
   * which the bind variables is listed dictates which method parameter value is set as a value of which variable.
   * 
   * @return the names of any binding variables in the query, in the order their values appear in the parameter
   * list of the method definition
   */
  String[] bindVariables() default { };

  /**
   * @return true if the native SQL method is an update (INSERT/UPDATE/DELETE) 
   * as opposed to a lookup (SELECT)
   */
  boolean update() default false;
  
}
